Skip to content

docs: split the progress log out of CLAUDE.md into docs/progress/ - #110

Merged
StackOverFlow11 merged 1 commit into
mainfrom
docs/condense-claude-md
Jul 30, 2026
Merged

docs: split the progress log out of CLAUDE.md into docs/progress/#110
StackOverFlow11 merged 1 commit into
mainfrom
docs/condense-claude-md

Conversation

@StackOverFlow11

Copy link
Copy Markdown
Owner

为什么

CLAUDE.md(= AGENTS.md)在每个会话开始时被完整加载。它已经长到 398 行 / 170 KB(约 78k tokens,占 1M 上下文的 9%)——因为每个完成的阶段都把完整记录追加进去。这些记录有价值,但是按需查的历史,不是每一轮都要在场的东西

做了什么

把第 66–397 行逐字搬进 docs/progress/,按阶段切分;CLAUDE.md 只留每个会话都需要的:项目定位 / 7 层架构 / 编号的设计不变量(源码 docstring 按编号引用它们)/ correctness 红线 / 环境 / secret 纪律 / 开发约定 / 当前状态 / 常设授权 / 工作制度 / 方法论 / 档案索引 / 当前有效的披露与路线图

没有任何内容被改写或摘要掉。

之前 之后
CLAUDE.md 行数 398 151
CLAUDE.md 字节 170,316 14,469(−91.5%)

归档结构

文件 覆盖
docs/progress/README.md 索引 + 怎么用(grep 不整读)+ 未入 git 的本机权威文档清单
pr_ledger.md PR #1#107 台账(含 #38 保持 OPEN)
01_phase0_3_daily_pipeline.md Phase 0–3(PR #1#21
02_phase4_cache_and_intraday_i1_i4.md P4-1/4-2/4-3 + I1–I4(#23#31
03_intraday_i5.md I5a–I5f(#33#55
04_data_layer.md 数据层 D1–D5 + schema 守卫 + 全A(#41#61
05_minute_factors_eval_contract.md 评估契约 + 十一因子(#63#74
06_execution_basis_and_corrections.md VWAP/复权/除权审计/exec 改基准(#75#82
07_factor_layer_refactor.md 因子层重构 D0–D5 C4b(#84#107
08_gates_disclosures_roadmap.md 归档时点的质量门/披露/路线图原文

怎么验证没丢内容

不是靠肉眼比对:写了重建脚本,把各归档文件正文重新拼起来与原 CLAUDE.md 第 66–397 行逐行比较——

orig lines: 332  rebuilt: 332
EXACT MATCH: True
LEDGER EXACT: True

另外程序化确认 第 1–59 行与第 61–64 行逐字节未变(这段含被源码 docstring 按编号引用的 invariant #1/#2/#3,编号绝不能动)。唯一被替换的是第 60 行那条超长的 Git 条目 → 改成短版 + 指向 docs/progress/pr_ledger.md

防止它再长回去

归档小节里写明了规则:新阶段的详细记录写进 docs/progress/,不要写回 CLAUDE.mdCLAUDE.md 只维护三处随进度变化的内容(当前状态表 / 披露 / 路线图)。执行交接文档 §3 Step 3 与 §8 已同步更新。

Gates(lead 本地实跑)

  • pytest -p no:warnings2537 passed(与 main 基线一致,docs-only 变更)
  • ruff check . → All checks passed
  • cmp CLAUDE.md AGENTS.md → 逐字节相同
  • 无代码变更:diff 只含 CLAUDE.md / AGENTS.md / docs/progress/*

CLAUDE.md (= AGENTS.md) is auto-loaded in full at the start of every
session. It had grown to 398 lines / 170 KB (~78k tokens, 9% of a 1M
context) because every completed phase appended its full record to it.
Almost all of that is history: valuable, but needed on demand, not on
every turn.

Move lines 66-397 verbatim into docs/progress/, split by phase, and
keep in CLAUDE.md only what every session needs: positioning, the
7-layer architecture, the numbered design invariants (referenced by
name from source docstrings), the correctness red lines, environments,
the secret discipline, dev conventions, the current status snapshot,
the standing authorizations, the working protocol, the methodology
rules, an index of the archive, and the disclosures/roadmap that are
currently in force.

Nothing is rewritten or summarised away. A reconstruction script
verified that concatenating the archive bodies reproduces the original
332 lines exactly, line for line, and the PR ledger line likewise.
Lines 1-59 and 61-64 of CLAUDE.md are byte-identical to before; only
the Git bullet was replaced by a shorter one pointing at
docs/progress/pr_ledger.md.

CLAUDE.md: 398 -> 151 lines, 170316 -> 14469 bytes.

To keep it from growing back, the archive section states the rule
explicitly: new phase records go to docs/progress/, and CLAUDE.md
maintains only three moving parts (status table, disclosures,
roadmap).

Gates: pytest 2537 passed, ruff clean, CLAUDE.md == AGENTS.md.
@StackOverFlow11
StackOverFlow11 merged commit 8ea5d68 into main Jul 30, 2026
@StackOverFlow11
StackOverFlow11 deleted the docs/condense-claude-md branch July 30, 2026 12:57
StackOverFlow11 added a commit that referenced this pull request Jul 30, 2026
docs: record PRs #108-#110 in the ledger and date the status gates
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant